[ Proud like a god ] Scripting Guide: Lesson5

[ Intro ] [ Lesson1 ] [ Lesson2 ] [ Lesson3 ] [ Lesson4 ] [ Lesson5 ] [ Lesson6 ] [ Lesson7 ] [ Lesson8 ]

Animation and activation

The most complex way we'll normally animate a unit is when it goes from a starting state to an active one, like the Zeus preparing it's gun. Often a unit will remain in this active state until it's stopped repeatedly shooting etc, it does not turn off and on after each shot. To understand how we switch between such states, we'll start by opening the example named armrad.bos. This is the Arm Radar unit and we'll use it to explain the obvious on/off states of radar units.

StateChg.h

This include is often how we'll change a unit's state via the script. If we open it in a text editor, we'll find these comments near the top:

// Due to limitations of the scripting language, this file must be included twice. The
// first time must be where the static variables are declared. The second time must be
// where the functions are defined (and of course before they are called.)
// The Following macros must be defined: ACTIVATECMD and DEACTIVATECMD. They are the commands
// to run when the units is activated or deactivated.

This explains why you'll find the StateChg.h included before the Go() and Stop() functions, and after the ACTIVATECMD and DEACTIVATECMD macros which call them.

Next it's important to remember to place call-script InitState(); in Create(), it's vital to how StateChg.h works.

Activate() & Deactivate()

These functions are called by TA when the On/Off button is pushed. You could also change some variable states here but in this case we're just requesting to appropriate state changes, via start-script RequestState(state);
In TA scripts, you may see state as either 0/1, or ACTIVE/INACTIVE. It's important to note another quirk from StateChg.h, and that is:

#define ACTIVE 0
#define INACTIVE 1

This means that requesting 0 means to turn the unit on, and 1 is off. Remember this and you'll be less confused later.

How it all works

When the player pushes the On/Off button ingame, in this case let's say to turn on, Activate() is called. This in turn requests that StateChg.h make the unit ACTIVE. In the course of doing this, it starts the ACTIVATECMD macro which calls the Go() function. It's this Go() function which starts the spinning radar animation. After this is completed, StateChg.h has finished turning the unit on, and ingame the radar will be working as normal.

Now I advise you to read the following text about Cache and Shading before moving on to Lesson6, Nanolathing (building).

Cache and Shade

Something else that is often vital to achieving decent animations is making sure moving pieces are shown to be moving ingame, and that we don't burden the engine which shadow calculations while pieces are moving. Because stationary units are normally still, all their pieces are presumed to be non-moving, and are cached by the engine to reduce the position-checking load when updating the ingame image. However, this can cause animations to appear as instantanious movements from origin to destination unless TA is told to actively check the piece's position.

To do this we state dont-cache piecename; at the start of the movement, and it's kind to tell TA to re cache piecename; once the movement is done (again to reduce the load on the non-hardware-accelerated graphics engine).

Similarly we dont-shade and shade moving pieces, and this can be seen in the current example, the Arm Radar script.

Metal Extracting and Wind animations

Some other actions of stationary units are those of resource generators, such as Metal Extractors and Wind Generators. These units have special features to interact with the terrain, such as mine faster if there's more metal, or turn and face the wind. These are controlled by the script too, as you'll see if you open the armmex.bos example.

Because the value of a metal deposit is not uniform in a TA map, so the rate at which the Mex's rotor spins is not fixed. In this case it's replaces with the variable named spinspeed. Strangly the rate of acceleration is similarly a variable named spinaccn, but is given fixed value, so this just seems like redundant code. The spinspeed is stared at 0, but when the unit ready, that value is changed by the following function:

SetSpeed(the_speed)
{
spinspeed = the_speed * 45;
return (0);
}

Why the_speed is multiplied by 45, I'm not sure. This other bit of redundant code seems to imply that there the metal coding of the TA engine had/would have some more features. The rest of the Arm Mex's script is very similar to the Arm Radar's, so nothing else is new.

Now for Wind Generators, and the armwin.bos example. Similar to the Mex script, SetSpeed(fanspeed) is used to get the correct animation speed, and SetDirection(dir) for the direction. For more realistic animation we wait until there's no more building to be done (get BUILD_PERCENT_LEFT == 0, the unit's complete) before getting these values.

In the Wind Gen's case, the strenght and direction of the wind can also change after the unit's been built, so the new value is used in an animation statement to update the unit's ingae actions. We also store it's last know states in lastfanspeed and lastdir, so that when the Wind Gen. is turned Off and then On, it has a decent value to spin and turn to, before those are updated again by the engine.